package com.gagakuai.concurrent;

import java.util.Collection;
import java.util.Queue;
import java.util.concurrent.TimeUnit;

/*
 * 单向阻塞队列
 * 主要特征：
 * 1：阻塞队列是线程安全的，入队/出队互不干涉
 * 2.在不满足入队/出队条件时，可以选择阻塞操作线程，
 * 或选择快速失败
 *
 * @author: houhong
 */
public interface BlockingQueue<E> extends Queue<E> {

    /*=================入队====================*/

    /*
     * 入队，无法入队时扩容或阻塞
     */
    void put(E e) throws InterruptedException;

    /*
     * 入队，无法入队时扩容或抛异常，不阻塞
     */
    boolean add() throws InterruptedException;

    /*
     * 入队，无法入队时扩容或返回false，不阻塞
     */
    @Override
    boolean offer(E e);

    /*
     * 入队，无法入队时扩容，或阻塞一段时间，超时后无法入队则返回false
     */
    boolean offer(E e, long timeout, TimeUnit unit) throws InterruptedException;


    /*
     * 出队，无法出队时阻塞
     */
    E take() throws InterruptedException;


    /*
     * 出队，无法出队时阻塞一段时间，超时后无法出队则返回null
     */
    E poll(long timeout, TimeUnit unit) throws InterruptedException;

    /*
     * 移除，移除成功则返回true（该方法来自Collection）
     */
    @Override
    boolean remove(Object o);

    /*
     * 将队列中所有元素移除，并转移到给定的容器当中
     */
    int drainTo(Collection<? super E> c);


    /*
     * 将队列中前maxElements个元素移除，并转移到给定的容器当中
     */
    int drainTo(Collection<? super E> c, int maxElements);

    /*
    * 判断队列中是否包含指定的元素
    */
    @Override
    boolean contains(Object o);

    /*
     * 计算队列剩余空间，并转移到给定的容器当中
     */
    int remainingCapacity();


}